Prizm Content Connect
Viewing Sessions
Working with the Prizm Platform Services > Developer Reference - Prizm Services > PCC RESTful API > Viewing Sessions

To initiate a view, the following RESTful operations should be performed as detailed in the Prizm Services Sample discussion.

POST ViewingSession

The first step for viewing a document is to request a viewing session Identification JSON string. The body of the request is to send useful information about the document to the Prizm Services service which helps identify the document that will be uploaded to the service for conversion to a web compatible viewing format. The object to be posted here is the ViewSessionProperties resource which contains several properties.  

The origin property is a key pair dictionary to contain any useful arbitrary data about the document. The Prizm Services sample uses ipAddress, hostname, and sourceDocument for identification purposes, but any arbitrary data can be used that helps identify or characterizes the document.  

The render property is important for storing information for client-side rendering. It stores rendering information for both the flash client and HTML client. For flash see the Basic Document Conversion Parameters on enterprise. For HTML5, the new Html5RenderProperties class object has properties to set output dpi resolution and whether raster output should always be used (no SVG format output). 

The externalId property and tenantId should also be set. Typically, the externalId is a unique value which makes it easier to connect items in the server log to that which is in the caller’s log but is not used for any particular purpose and the same goes for tenantId. Please look at the Prizm Services sample for more information on using this RESTful API.

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession

Parameters

None

Request Body

In the request body, supply a ViewingSessionProperties resource with the following optional properties:

Property Name

Value

Description

origin

List

A list of key-value pairs containing user-specific data. This is useful for tracking information pertinent to the request, like IP address, Host Name, and any other useful bits of information.

render

Nested Object

The object that describes rendering options.

render.flash

Nested Object

The object that describes rendering options for the Flash viewer.

render.flash.optimizationLevel

Integer

Specifies the optimization level used during SWF generation for the Flash viewer:

  • 0 = No compression for text and images.
  • 1 = Text is preserved while everything else is converted to JPEG compressed images.
  • 2 = All content is converted into a single SWF, only links are preserved.

render.html5

Nested Object

The object that describes rendering options for the HTML5 viewer.

render.html5.alwaysUseRaster

Boolean

Forces Prizm Services to always provide raster image data to the HTML5 viewer instead of SVG, even if the client supports viewing SVG data.

render.html5.rasterResolution

Integer

Deprecated. Setting this property no longer has any effect.

password

String

Specifies the password to open password-protected PDF documents.

serverCaching

String

This optional property determines whether or not the conversion output is cached for potential reuse by other viewing sessions. Valid values are:

  • "full" means that the output will be cached on the server. (default)
  • "none" means that the output will not be cached on the server.

By default, the output of the document conversion process is cached on the server for potential reuse in future viewing sessions created to view the same document. This assumes that a document is likely to be viewed multiple times across different viewing sessions. If this is not the case (e.g., a new viewing session is always a new document), you can save disk space on the server by explicitly setting the serverCaching property to "none" to prevent the caching of the output on the server.

watermarkText

String

Specifies the text to use for watermarking as supported by the Flash viewer. This property is not currently used for the HTML5 viewer when displaying SVG content.

externalId

String

If the documentSource property is set to "api", empty, or is null, this property is not used by Prizm Services and can be used to store a value of your choosing for the viewing session. This value could be useful for identifying requests in Prizm Services log files or other purposes you find useful.

If the documentSource property is set to "http" or "file", then this property must define the URL or local file path of the source document that Prizm Services will retrieve. See the How to Transfer Your Document to Prizm Services topic for more details. 

tenantId

String

This is an ID for a tenant. Tenants are not a formal concept in this system and should be monitored and maintained in the calling system. However, having this data available will allow some optional behavior. For example, with this information, it would be possible to ensure some level of isolation between tenants.

attachmentIndex

Integer

Used for documents with attachment documents, like .MSG and .EML types. Otherwise, this value will typically be 0 for other document types.

attachmentDisplayName

String

Used for documents with attachment documents, like .MSG and .EML types. Provides the display name of the attachment.

countOfInitialPages

Integer

The default value is 0, which will cause Prizm Services to behave in its default manner converting all pages (running enterprise=3) of the document as soon as any page is requested. Setting countOfInitialPages to a value greater than 0 will instruct Prizm Services to use two separate enterprise=3 operations: one to convert pages 0 through n-1 (where "n" the supplied value) and a second conversion to process pages "n" through the end of the document. The second conversion will only occur when content that has not been converted is requested. This should allow the first "n" pages to be created and delivered to the client without forcing the entire document to be converted.

documentSource

String

This property tells Prizm Services how it should expect to get the source document for a viewing session. The following values are supported:

  • "api" means that the document will be sent to Prizm Services using the PUT HTTP request. This is the default and will be used if this property is null or empty.
  • "http" means that Prizm Services should download the source document from the URL provided in the "externalId" property.
  • "file" means that Prizm Services should create a copy of the source document from the local file path provided in the "externalId" property.

See the How to Transfer Your Document to Prizm Services topic for more details.              

documentExtension

String

Defines the extension of the document specified in the externalId property. The Requirement of this property depends on whether Format Detection is enabled (default) or disabled.

If Format Detection is disabled, then this property is only required if documentSource is "http" or "file" and the file name specified in externalId does not contain a valid document extension. If the file name specified inexternalId contains a valid extension for the document, this property can be left unset.

If Format Detection is enabled (default), then this property is optional with the following restrictions:

  • If the file is uniquely identified by the Format Detection process and no documentExtension is provided, the detected documentExtension will be used. 
  • If the file is uniquely identified by the Format Detection process and a documentExtension is provided but differs from the detected documentExtension, the detected documentExtension will be used. 
If the file is not identified by the Format Detection process and a documentExtension is provided, the provided documentExtension will be used.

The preceding "." should NOT be included in the extension value, otherwise an exception will be thrown and return 500 status from the POST HTTP request.

startConverting

String

This property determines when the process to generate pages for viewing is started. This property requires that documentSource is "http" or "file" and contentType is set to a valid value. Valid values are:

  • "initialPages" means the process to generate pages for viewing is started during the initial POST /ViewingSession request.
  • "none" means the process to generate pages for viewing is started later during a request to POST /ViewingSession/{id}/Notification/SessionStarted, GET /Page or GET /PageAttributes, whichever comes first.

contentType

String

This property sets the type of pages that are generated for viewing if startConverting is not "none". Valid values are:

  • "png" means that PNG pages will be generated for viewing.
  • "svg" means SVG pages will be generated for viewing.
  • "svga" means SVG pages will be generated for viewing, but SVG will be optimized to reduce payload size. Note: "svga" is not supported by the Internet Explorer 10 browser.
  • "swf" means SWF pages will be generated for viewing.
watermarks Array The array of objects which describe the watermarks to apply to the viewing session. This object is optional. The presence of valid watermark objects enables watermarking for the viewing session.
watermarks[n].type String

This property determines the type of watermark this object defines. The value of this property will determine what remaining properties are important according to the type.

Valid values:

  • "text" means that the current watermark object defines a watermark that will display horizontal text on all pages in the viewing session.
  • "diagonalText" means that the current watermark object defines a watermark that will display diagonal text on all pages in the viewing session.
  • "image" means that the current watermark object defines a watermark that will display an image on all pages in the viewing session.
Default value: N/A, this property is required.
watermarks[n].opacity Number

This property determines how transparent or opaque a watermark appears over the page content. A value of 0.0 is completely transparent (not visible). A value of 1.0 is completely opaque.

Valid values: 0.0 to 1.0

Default value: 1.0
watermarks[n].text String

This property determines the text string that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values: Any valid text string

Default value: N/A, this property is required when type is "text" or "diagonalText".

See the How to Watermark Content in a Viewing Session topic for more information about special properties of the text string.
watermarks[n].color String

This property determines the color of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values: Any valid CSS color name (i.e. "red", "darkblue") or HEX value ("#FF0000")

Default value: "black"
watermarks[n].fontFamily String

This property determines the font name of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values; Any valid font family name

Default: Browser default font

See the How to Watermark Content in a Viewing Session topic for more information about the use of fonts.
watermarks[n].fontSize String

This property determines the font size of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values: A string containing a positive, non-zero decimal number followed by "pt" (i.e. "27.5pt").

Default value: "12pt"
watermarks[n].fontStyle String

This property determines the style of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values:

  • "normal" means that the  text will have no additional styling applied.
  • "italic" means that the text will be italicized.

Default value: "normal"
watermarks[n].fontWeight String

This property determines the weight of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid Values:

  • "normal" means that the  text will be a normal weight.
  • "bold" means that the text will be bold weight.
Default value: "normal"
watermarks[n].textDecoration String

This property determines the decoration applied to the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid Values:

  • "none" means that the  text will have no additional decoration.
  • "underlined" means that the text will be underlined.
Default value: "none"
watermarks[n].horizontalAlign String

This property determines the horizontal alignment within the page for "text" and "image" watermark types. This property does not apply to "diagonalText" watermarks. For "left" and "right" values, sensible margins will be used so that the edge of the watermark does not fall on the very edge of the page.

Valid Values:

  • "left" means that the  watermark will be aligned on the left side of the page. Further, multi-line text watermarks will also have left alignment.
  • "center" means that the  watermark will be aligned on the center of the page. Further, multi-line text watermarks will also have center alignment.
  • "right" means that the  watermark will be aligned on the right side of the page. Further, multi-line text watermarks will also have right alignment.

Default value: "center"
watermarks[n].verticalAlign String

This property determines the vertical alignment within the page for "text" and "image" watermark types. This property does not apply to "diagonalText" watermarks. For "top" and "bottom" values, sensible margins will be used so that the edge of the watermark does not fall on the very edge of the page.

Valid Values:

  • "top" means that the  watermark will be aligned on the top of the page.
  • "middle" means that the  watermark will be aligned on the middle of the page.
  • "bottom" means that the  watermark will be aligned on the bottom of the page.

Default value: "middle"
watermarks[n].slope String

This property determines the angle that the text is drawn for "diagonalText" watermark types. This should not be set for "image" and "text" watermark types.

Valid Values:

  • "up" means that the  diagonal text will start in the lower-left corner of the page and extend to the upper-right corner of the page.
  • "down" means that the  diagonal text will start in the upper-left corner of the page and extend to the lower-right corner of the page.
Default value: "up"
watermarks[n].autoSize String

This property determines how an "image" watermark type will be sized to fill a page. If specified, any values for scale, verticalAlign, and horizontalAlign will be ignored. Note that the sensible automatic margins mentioned above for verticalAlign and horizontalAlign do not apply when auto-sizing an image watermark. In this case, the image should reach the very edge of the page. This should not be set for "text" and "diagonalText" watermark types.

Valid Values:

  • "fit" means the image is scaled as far as possible while maintaining aspect ratio and without allowing any of the image to go beyond the edge of the page.
  • "fill" means the image is scaled so that it completely fills the entire page with aspect ratio maintained. Some of the image may fall off the edge of the page, but the entire page is guaranteed to be covered by some part of the image.
  • "stretch" means the image is resized to be the same as the page. Aspect ratio is ignored.

Default value: N/A, the scale, verticalAlign, and horizontalAlign properties will be used if unset.
watermarks[n].scale Number

This property determines the size of images that are located using the verticalAlign and/or horizontalAlign properties. A scale value may be specified as a numeric value between 0.0 and 1.0. The value 1.0 indicates the image will be scaled to the size of the page and 0.0 indicates the image will be scaled infinitesimally small and will not be rendered. This should not be set for "text" and "diagonalText" watermark types.

Valid values: 0.0 to 1.0

Default value: 0.25 as long as autoSize is not set.
watermarks[n].src String

This property determines the source of the image data for "image" watermark types. This should not be set for "text" and "diagonalText" watermark types.

Note: The image watermark source must be a PNG. If other image formats are provided it will cause invalid watermarks to be created.

Valid values:

  • A work file ID referencing a valid work file. See the Work File topic for more information about creating work files and obtaining their IDs.
  • A URL specifying an absolute location with an HTTP or HTTPS scheme. This URL must be accessible from the server hosting the PCC RESTful Web Services.
Default value: N/A, required for "image" watermark types.
pageContentEncryption String

Allows content encryption to be enabled or disabled for a single viewing session, overriding the PCC Services configuration on the server. See the "EncryptPageContent" setting in the PCCIS Configuration Options topic for more details about enabling or disabling content encryption on the server. 

Valid values for this property are:

  • "enabled" means that the server will encrypt page content in the responses for the current viewing session. This value will override the PCC Services configuration setting.
  • "disabled" means that the server will NOT encrypt page content in the responses for the current viewing session. This value will override the PCC Services configuration setting.
  • "default" means that the PCC Services configuration setting will be used to determine whether or not it encrypts page content in the responses for the current viewing session. This is the default behavior.

Setting this property to null or not including it at all means the same as "default".

See the topic Enabling Content Encryption for more information about this feature.

 Additionally, the server configuration setting "ViewingSessionPropertyPageContentEncryption" can be used to limit the values of this property that the server will accept. A value outside of the acceptable values defined by this server configuration setting will cause an error and the viewing session will not be created. See the "ViewingSessionPropertyPageContentEncryption" setting in the PCCIS Configuration Options topic for more details about defining allowable values for this property.    

Response Body

If successful, this method returns the following properties:

Property Name

Value

Description

viewingSessionId

String

The ID for this new viewing session.
Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession
Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession
Content-Type: application/json
{
    "tenantId": "my application name",
    "externalId": "my-unique-document-name.docx",
    "render": {
        "flash": {
            "optimizationLevel": 1
        },
        "html5": {
            "alwaysUseRaster": false
        }
    },
    "watermarks": [
        {
            "type": "text",
            "opacity": 0.6,
            "text": "jdoe\n67.79.169.114\n11/13/2014 2:24 PM\nNOT FOR DISTRIBUTION",
            "color": "red",
            "fontFamily": "Consolas",
            "fontSize": "16pt",
            "fontWeight": "bold",
            "verticalAlign": "bottom",
            "horizontalAlign": "right"
        }
    ]
}

 

Example Response
Copy Code 
{"viewingSessionId":"8091681f-15bf-4150-94a0-3ff7f2acd42d"}

PUT ViewingSession/u{ViewingSessionID}/SourceFile?FileExtension={FileExtension}

A document source is uploaded to the Prizm Services by writing the contents into the request stream using the viewing session ID from the previous viewing session ID request. 

Http Method

PUT

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/SourceFile?FileExtension={FileExtension}

Parameters

ViewingSessionID

The ID of the viewing session associated with the request.

FileExtension

This is the file extension of the document being uploaded. This parameter may or may not be required depending on the file type and whether Format Detection is enabled. Note that the extension must not include the leading period (for example, 'jpg' is accepted but '.jpg' will return a 400 HTTP status). Extensions are not case sensitive. If Format Detection is disabled, the FileExtension must be provided. 

If Format Detection is enabled (default), the use of the FileExtension is as follows:

  • If the file is uniquely identified by the Format Detection process and no FileExtension is provided, the detected FileExtension will be used.
  • If the file is uniquely identified by the Format Detection process and a FileExtension is provided but differs from the detected FileExtension, the detected FileExtension will be used.   
  • If the file is not identified by the Format Detection process and a FileExtension is provided, the provided FileExtension will be used.
  • If the file is not identified by the Format Detection process and no FileExtension is provided, an error code of 'UnrecognizedFileFormat' will be returned with a HTTP 580 status.

Request Body

In the request body, supply the document data to be uploaded.

Response Body

Empty.

Example
Copy Code 
PUT http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/SourceFile?FileExtension=doc

 

Example Response
Copy Code 
Empty

GET ViewingSession/u{ViewingSessionID}/SourceFile{?ContentDispositionFilename}

Returns the original source document for a valid, active viewing session. The document returned will be an identical copy of the document originally provided to PCCIS; no conversions to other formats are supported.

The response will set the Content-Type header value to the registered MIME type associated with document extension of the original document. If a registered MIME type is not found, the value "application/octet-stream" is used. 

Http Method

GET

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/SourceFile

Parameters

Name Description Details
ViewingSessionID ID of the viewing session.

string, required

Example:

uW1ZpNTSfU139Zh3dfdhwbff
ContentDispositionFilename

Name to use for the filename attribute in the Content-Disposition response header.

The default value is "file-{WorkFileId}.{extension}".

The file extension of the source file will automatically be added to the Content-Disposition filename.

string, optional

Example:

MonthlySalesReport

Request Body

None

Response Body

The document data, in its original format.

Example
Copy Code 
GET http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/SourceFile
Example Response
Copy Code 
200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=MontlySalesReport.pdf
[Document Data]

POST ViewingSession/u{ViewingSessionID}/Notification/SessionStarted

This RESTful API requests the Prizm Services service to begin conversion of the document to either HTML or Flash format. The body posted to the service will have an object which indicates the preference. The object property, viewer, will either be set to "HTML5" or "Flash". 

A User-Agent header must be passed in with the viewer property or the session will fail.

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/Notification/SessionStarted

Parameters

ViewingSessionID

The ID of the viewing session associated with the request.

Request Body

In the request body, supply an object with the following optional property:

Property Name

Value

Description

viewer

String

Specify the type of viewer being used. The supported values are:

  • "HTML5"
  • "Flash"

The default value is "HTML5".

Response Body

Empty.

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/Notification/SessionStarted

 

Example Response
Copy Code 
Empty

POST ViewingSession/u{ViewingSessionID}/Notification/SessionStopped

This request is used to stop, or invalidate, an active viewing session. This can be useful in situations when a viewing session is started but something prevents the document from being uploaded to the PCC RESTful Web Services successfully. You may also have a need in your application to stop a viewing session after a user is done with it and before the viewing session expires.

The parameters provided in the body of the request should be set with some consideration within your application. The httpStatus and endUserMessage property values specified in the body of this request will determine the HTTP status code and reason phrase that will be returned in the response for any request of the viewing session once this request has been issued.

For example, if this request is sent with httpStatus = 504 and endUserMessage = "Session is no longer available" and then a request is made to get page 0 for the same viewing session, the response status of that request will be 504 Session is no longer available and the page content will not be delivered.

This allows you to explicitly handle the error case when requests are sent after the session has been stopped. 

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/Notification/SessionStopped

Parameters

ViewingSessionID

The ID of the viewing session associated with the request.

Request Body

In the request body, optionally supply a SessionStoppedProperties resource with the following optional properties:

Property Name Value Description
endUserMessage String A message suitable for display to the end user to be returned if any attempt to use the session is made after the session has been stopped. Default is "Session is stopped".
httpStatus Integer The http status suitable for display to the end user to be returned if any attempt to use the session is made after the session has been stopped. Default is 580.
accusoftErrorNumber Integer A custom Accusoft error number that should be sent back to the end user to be returned if any attempt to use the session is made after the session has been stopped. Default is 580.
serverLogMessage String A message that should be placed into the server's log file when the session is stopped. Default is "The viewing session is stopped on request from the client".

Response Body

Empty.

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/Notification/SessionStopped
{
  "endUserMessage": "Session no longer available",
  "httpStatus": 504,
}

 

Example Response
Copy Code 
200 OK

PUT /PCCIS/V1/ViewingSession/u{id}/SourceRef

Assigns an existing work file to be used as the source document for this viewing session. This can be particularly useful when you want to avoid repeatedly uploading the same source file to the back end.

Request

Query Parameters

None

Request Headers

None

Request Body

A JSON object specifying a refType of "workFile" and the file id of the work file to use. 

Name

Description

Details

refType

Must be set to "workFile".

string, required

fileId

The id of the work file to use as a source document.

string, required
Example
Copy Code 
{
      "refType": "workFile",
      "fileId": "mUiXiqsQuevJKO9Swa32Bd"
}

Successful Response

HTTP Status Code

200

Response Headers

None

Response Body

Empty

Error Response: Work file not found

If the work file you specified has expired or does not exist, you will receive an HTTP 480 response with a JSON object containing an errorCode of "NotFound".

HTTP Status Code

480

Response Headers 

Name

Description

Content-Type

Will be set to "application/json".

Response Body

Example
Copy Code 
HTTP 480
Content-Type: application/json
{
     "errorCode": "NotFound",
     "errorDetails": {
         "in": "body",
         "at": "fileId"
     }
}

Error Response: Cannot change document once set

Once a viewing session is given a source document, that document cannot be changed. If a viewing session already has a source document and you attempt to assign a document by reference, you will receive an HTTP 480 error response with an errorCode of "CannotChangeDocument":

Example
Copy Code 
HTTP 480
Content-Type: application/json
{
     "errorCode": "CannotChangeDocument",
     "errorDetails": {
         "in": "body",
         "at": "fileId"
     }
}

 

GET /PCCIS/V1/ViewingSession/u{id}/FileId

Returns the id of the work file which is being used for this viewing session. 

Regardless of how a source document is provided, whether it is uploaded directly or whether an existing work file is used by reference, once the viewing engine has acquired the source document it will first ensure that a copy of it is present in the work file system.

Getting the work file id for a viewing session can be particularly helpful if you have uploaded a file directly to a viewing session and then want to reuse that file for a new viewing session without uploading it again.

Request

Query Parameters

None

Request Headers

None

Response

HTTP Status Codes

200

480 - When a document has not been provided yet.

Response Headers

Name

Description

Content-Type

Will be set to "application/json".

Response Body

When a source document exists:

As long as this viewing session has a source document, the response will contain a work file id:

Example
Copy Code 
HTTP 200
Content-Type: application/json
{
      "fileId": "mUiXiqsQuevJKO9Swa32Bd"
}

When a source document has not been provided:

If you just created a viewing session and have not yet provided a source document (either by upload or reference), then this URL will respond with:

Example
Copy Code 
HTTP 480
Content-Type: application/json
{
      "errorCode": "DocumentNotProvidedYet",
      "errorDetails": {
          "in": "body",
          "at": "fileId"
      }
}

 

 

 

©2015. Accusoft Corporation. All Rights Reserved.

Send Feedback